#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
模板方法模式 (Template Method Pattern) - Python实现详解

概述引导：
模板方法模式在一个方法中定义一个算法的骨架，而将一些步骤延迟到子类中。
模板方法使得子类可以不改变一个算法的结构即可重定义该算法的某些特定步骤。

学习要点：
1. 传统模板方法实现
2. 抽象基类和钩子方法
3. 函数式模板方法
4. 装饰器模板方法
5. 策略与模板方法结合

Java对比要点：
- Java使用抽象类定义模板方法
- Python可以使用函数和装饰器实现
- Python支持更灵活的钩子机制
- Python的动态特性简化模板定制

关键理解：
模板方法定义算法骨架，Python的灵活性使模板更易扩展和定制。
"""

from abc import ABC, abstractmethod
from typing import Any, Callable, Dict, List, Optional, Union, Tuple
from dataclasses import dataclass, field
from enum import Enum, auto
from datetime import datetime, timedelta
import time
import json
import logging
import os
import hashlib
import csv
import xml.etree.ElementTree as ET
from functools import wraps
import threading
import asyncio
from pathlib import Path


# ============= 传统模板方法模式 =============

class DataProcessor(ABC):
    """
    数据处理器抽象基类 - 传统模板方法模式
    
    定义数据处理的算法骨架：
    1. 读取数据
    2. 验证数据
    3. 处理数据
    4. 保存结果
    
    Java对比：
    - Java使用abstract class和abstract method
    - Python使用ABC和abstractmethod装饰器
    """
    
    def process_data(self, source: str, target: str) -> Dict[str, Any]:
        """
        模板方法 - 定义算法骨架
        
        这是模板方法模式的核心，定义了处理流程的步骤
        """
        print(f"\n开始处理数据: {source} -> {target}")
        
        start_time = time.time()
        result = {
            'source': source,
            'target': target,
            'start_time': datetime.now(),
            'steps': []
        }
        
        try:
            # 步骤1: 读取数据
            print("步骤1: 读取数据")
            data = self.read_data(source)
            result['steps'].append('read_data')
            result['data_size'] = len(data) if data else 0
            
            # 步骤2: 验证数据（钩子方法）
            if self.should_validate():
                print("步骤2: 验证数据")
                self.validate_data(data)
                result['steps'].append('validate_data')
            
            # 步骤3: 预处理（钩子方法）
            if self.should_preprocess():
                print("步骤3: 预处理数据")
                data = self.preprocess_data(data)
                result['steps'].append('preprocess_data')
            
            # 步骤4: 处理数据
            print("步骤4: 处理数据")
            processed_data = self.process_core_logic(data)
            result['steps'].append('process_core_logic')
            result['processed_size'] = len(processed_data) if processed_data else 0
            
            # 步骤5: 后处理（钩子方法）
            if self.should_postprocess():
                print("步骤5: 后处理数据")
                processed_data = self.postprocess_data(processed_data)
                result['steps'].append('postprocess_data')
            
            # 步骤6: 保存结果
            print("步骤6: 保存结果")
            self.save_data(processed_data, target)
            result['steps'].append('save_data')
            
            # 步骤7: 清理（钩子方法）
            if self.should_cleanup():
                print("步骤7: 清理资源")
                self.cleanup()
                result['steps'].append('cleanup')
            
            result['success'] = True
            result['end_time'] = datetime.now()
            result['duration'] = time.time() - start_time
            
            print(f"处理完成，耗时: {result['duration']:.2f}秒")
            
        except Exception as e:
            result['success'] = False
            result['error'] = str(e)
            result['end_time'] = datetime.now()
            result['duration'] = time.time() - start_time
            
            print(f"处理失败: {e}")
            
            # 错误处理（钩子方法）
            self.handle_error(e, result)
        
        return result
    
    # 抽象方法 - 子类必须实现
    @abstractmethod
    def read_data(self, source: str) -> Any:
        """读取数据 - 抽象方法"""
        pass
    
    @abstractmethod
    def process_core_logic(self, data: Any) -> Any:
        """核心处理逻辑 - 抽象方法"""
        pass
    
    @abstractmethod
    def save_data(self, data: Any, target: str) -> None:
        """保存数据 - 抽象方法"""
        pass
    
    # 钩子方法 - 子类可以选择性重写
    def should_validate(self) -> bool:
        """是否需要验证数据"""
        return True
    
    def should_preprocess(self) -> bool:
        """是否需要预处理"""
        return False
    
    def should_postprocess(self) -> bool:
        """是否需要后处理"""
        return False
    
    def should_cleanup(self) -> bool:
        """是否需要清理"""
        return False
    
    def validate_data(self, data: Any) -> None:
        """验证数据 - 默认实现"""
        if not data:
            raise ValueError("数据为空")
    
    def preprocess_data(self, data: Any) -> Any:
        """预处理数据 - 默认实现"""
        return data
    
    def postprocess_data(self, data: Any) -> Any:
        """后处理数据 - 默认实现"""
        return data
    
    def cleanup(self) -> None:
        """清理资源 - 默认实现"""
        pass
    
    def handle_error(self, error: Exception, result: Dict[str, Any]) -> None:
        """错误处理 - 默认实现"""
        logging.error(f"数据处理错误: {error}")


# ============= 具体实现类 =============

class CSVProcessor(DataProcessor):
    """
    CSV数据处理器
    
    实现CSV文件的读取、处理和保存
    """
    
    def __init__(self, delimiter: str = ',', encoding: str = 'utf-8'):
        self.delimiter = delimiter
        self.encoding = encoding
        self.temp_files: List[str] = []
    
    def read_data(self, source: str) -> List[Dict[str, str]]:
        """读取CSV数据"""
        data = []
        try:
            with open(source, 'r', encoding=self.encoding) as file:
                reader = csv.DictReader(file, delimiter=self.delimiter)
                data = list(reader)
            print(f"读取CSV文件: {len(data)}行数据")
        except FileNotFoundError:
            raise FileNotFoundError(f"CSV文件不存在: {source}")
        except Exception as e:
            raise Exception(f"读取CSV文件失败: {e}")
        
        return data
    
    def process_core_logic(self, data: List[Dict[str, str]]) -> List[Dict[str, str]]:
        """CSV核心处理逻辑"""
        processed_data = []
        
        for row in data:
            # 示例处理：清理空白字符，转换为小写
            processed_row = {}
            for key, value in row.items():
                clean_key = key.strip().lower()
                clean_value = value.strip() if value else ''
                processed_row[clean_key] = clean_value
            
            processed_data.append(processed_row)
        
        print(f"处理CSV数据: {len(processed_data)}行")
        return processed_data
    
    def save_data(self, data: List[Dict[str, str]], target: str) -> None:
        """保存CSV数据"""
        if not data:
            print("没有数据需要保存")
            return
        
        try:
            # 确保目标目录存在
            os.makedirs(os.path.dirname(target), exist_ok=True)
            
            with open(target, 'w', encoding=self.encoding, newline='') as file:
                if data:
                    fieldnames = data[0].keys()
                    writer = csv.DictWriter(file, fieldnames=fieldnames, delimiter=self.delimiter)
                    writer.writeheader()
                    writer.writerows(data)
            
            print(f"保存CSV文件: {target}")
        except Exception as e:
            raise Exception(f"保存CSV文件失败: {e}")
    
    def should_preprocess(self) -> bool:
        """CSV需要预处理"""
        return True
    
    def should_cleanup(self) -> bool:
        """CSV需要清理临时文件"""
        return len(self.temp_files) > 0
    
    def preprocess_data(self, data: List[Dict[str, str]]) -> List[Dict[str, str]]:
        """CSV预处理：过滤空行"""
        filtered_data = []
        for row in data:
            # 过滤完全空的行
            if any(value.strip() for value in row.values()):
                filtered_data.append(row)
        
        print(f"预处理过滤: {len(data)} -> {len(filtered_data)}行")
        return filtered_data
    
    def cleanup(self) -> None:
        """清理临时文件"""
        for temp_file in self.temp_files:
            try:
                if os.path.exists(temp_file):
                    os.remove(temp_file)
                    print(f"删除临时文件: {temp_file}")
            except Exception as e:
                print(f"删除临时文件失败: {e}")
        
        self.temp_files.clear()


class JSONProcessor(DataProcessor):
    """
    JSON数据处理器
    
    实现JSON文件的读取、处理和保存
    """
    
    def __init__(self, indent: int = 2, ensure_ascii: bool = False):
        self.indent = indent
        self.ensure_ascii = ensure_ascii
        self.schema: Optional[Dict[str, Any]] = None
    
    def read_data(self, source: str) -> Union[Dict[str, Any], List[Any]]:
        """读取JSON数据"""
        try:
            with open(source, 'r', encoding='utf-8') as file:
                data = json.load(file)
            
            data_type = type(data).__name__
            size = len(data) if isinstance(data, (list, dict)) else 1
            print(f"读取JSON文件: {data_type}, {size}个元素")
            
            return data
        except FileNotFoundError:
            raise FileNotFoundError(f"JSON文件不存在: {source}")
        except json.JSONDecodeError as e:
            raise ValueError(f"JSON格式错误: {e}")
        except Exception as e:
            raise Exception(f"读取JSON文件失败: {e}")
    
    def process_core_logic(self, data: Union[Dict[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
        """JSON核心处理逻辑"""
        if isinstance(data, list):
            # 处理JSON数组
            processed_data = []
            for item in data:
                if isinstance(item, dict):
                    processed_item = self._process_json_object(item)
                    processed_data.append(processed_item)
                else:
                    processed_data.append(item)
            
            print(f"处理JSON数组: {len(processed_data)}个元素")
            return processed_data
        
        elif isinstance(data, dict):
            # 处理JSON对象
            processed_data = self._process_json_object(data)
            print("处理JSON对象")
            return processed_data
        
        else:
            # 其他类型直接返回
            return data
    
    def _process_json_object(self, obj: Dict[str, Any]) -> Dict[str, Any]:
        """处理JSON对象"""
        processed_obj = {}
        
        for key, value in obj.items():
            # 标准化键名
            clean_key = key.strip().lower().replace(' ', '_')
            
            # 处理值
            if isinstance(value, str):
                clean_value = value.strip()
            elif isinstance(value, dict):
                clean_value = self._process_json_object(value)
            elif isinstance(value, list):
                clean_value = [self._process_json_object(item) if isinstance(item, dict) else item for item in value]
            else:
                clean_value = value
            
            processed_obj[clean_key] = clean_value
        
        return processed_obj
    
    def save_data(self, data: Union[Dict[str, Any], List[Any]], target: str) -> None:
        """保存JSON数据"""
        try:
            # 确保目标目录存在
            os.makedirs(os.path.dirname(target), exist_ok=True)
            
            with open(target, 'w', encoding='utf-8') as file:
                json.dump(data, file, indent=self.indent, ensure_ascii=self.ensure_ascii)
            
            print(f"保存JSON文件: {target}")
        except Exception as e:
            raise Exception(f"保存JSON文件失败: {e}")
    
    def should_validate(self) -> bool:
        """JSON需要验证"""
        return True
    
    def should_postprocess(self) -> bool:
        """JSON需要后处理"""
        return True
    
    def validate_data(self, data: Union[Dict[str, Any], List[Any]]) -> None:
        """验证JSON数据"""
        super().validate_data(data)
        
        # 检查数据结构
        if not isinstance(data, (dict, list)):
            raise ValueError("JSON数据必须是对象或数组")
        
        # 如果有schema，进行schema验证
        if self.schema:
            self._validate_schema(data, self.schema)
    
    def _validate_schema(self, data: Any, schema: Dict[str, Any]) -> None:
        """简单的schema验证"""
        # 这里可以实现更复杂的schema验证逻辑
        if 'type' in schema:
            expected_type = schema['type']
            if expected_type == 'object' and not isinstance(data, dict):
                raise ValueError("期望对象类型")
            elif expected_type == 'array' and not isinstance(data, list):
                raise ValueError("期望数组类型")
    
    def postprocess_data(self, data: Union[Dict[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
        """JSON后处理：添加元数据"""
        metadata = {
            'processed_at': datetime.now().isoformat(),
            'processor': 'JSONProcessor',
            'version': '1.0'
        }
        
        if isinstance(data, dict):
            data['_metadata'] = metadata
        elif isinstance(data, list):
            # 对于数组，将元数据包装在外层对象中
            data = {
                'data': data,
                '_metadata': metadata
            }
        
        print("添加处理元数据")
        return data
    
    def set_schema(self, schema: Dict[str, Any]):
        """设置验证schema"""
        self.schema = schema


class XMLProcessor(DataProcessor):
    """
    XML数据处理器
    
    实现XML文件的读取、处理和保存
    """
    
    def __init__(self, root_tag: str = 'root'):
        self.root_tag = root_tag
        self.namespaces: Dict[str, str] = {}
    
    def read_data(self, source: str) -> ET.Element:
        """读取XML数据"""
        try:
            tree = ET.parse(source)
            root = tree.getroot()
            
            # 统计元素数量
            element_count = len(list(root.iter()))
            print(f"读取XML文件: 根元素={root.tag}, {element_count}个元素")
            
            return root
        except FileNotFoundError:
            raise FileNotFoundError(f"XML文件不存在: {source}")
        except ET.ParseError as e:
            raise ValueError(f"XML格式错误: {e}")
        except Exception as e:
            raise Exception(f"读取XML文件失败: {e}")
    
    def process_core_logic(self, data: ET.Element) -> ET.Element:
        """XML核心处理逻辑"""
        # 创建新的根元素
        processed_root = ET.Element(self.root_tag)
        
        # 递归处理元素
        self._process_element(data, processed_root)
        
        element_count = len(list(processed_root.iter()))
        print(f"处理XML数据: {element_count}个元素")
        
        return processed_root
    
    def _process_element(self, source_elem: ET.Element, target_parent: ET.Element) -> None:
        """递归处理XML元素"""
        # 创建新元素
        new_elem = ET.SubElement(target_parent, source_elem.tag)
        
        # 复制并清理文本内容
        if source_elem.text:
            new_elem.text = source_elem.text.strip()
        
        # 复制并处理属性
        for key, value in source_elem.attrib.items():
            new_elem.set(key, value.strip())
        
        # 递归处理子元素
        for child in source_elem:
            self._process_element(child, new_elem)
    
    def save_data(self, data: ET.Element, target: str) -> None:
        """保存XML数据"""
        try:
            # 确保目标目录存在
            os.makedirs(os.path.dirname(target), exist_ok=True)
            
            # 创建树并写入文件
            tree = ET.ElementTree(data)
            ET.indent(tree, space="  ", level=0)  # Python 3.9+
            tree.write(target, encoding='utf-8', xml_declaration=True)
            
            print(f"保存XML文件: {target}")
        except Exception as e:
            raise Exception(f"保存XML文件失败: {e}")
    
    def should_validate(self) -> bool:
        """XML需要验证"""
        return True
    
    def validate_data(self, data: ET.Element) -> None:
        """验证XML数据"""
        super().validate_data(data)
        
        if not isinstance(data, ET.Element):
            raise ValueError("数据必须是XML元素")
        
        # 检查根元素
        if not data.tag:
            raise ValueError("XML根元素标签不能为空")


# ============= 函数式模板方法 =============

def create_template_processor(read_func: Callable, process_func: Callable, save_func: Callable,
                            validate_func: Optional[Callable] = None,
                            preprocess_func: Optional[Callable] = None,
                            postprocess_func: Optional[Callable] = None,
                            cleanup_func: Optional[Callable] = None) -> Callable:
    """
    函数式模板方法 - Python特色实现
    
    使用函数组合创建数据处理模板
    
    Python优势：
    - 函数作为一等公民
    - 更灵活的组合方式
    - 减少类的层次结构
    """
    
    def template_processor(source: str, target: str, **kwargs) -> Dict[str, Any]:
        """模板处理器函数"""
        print(f"\n函数式模板处理: {source} -> {target}")
        
        start_time = time.time()
        result = {
            'source': source,
            'target': target,
            'start_time': datetime.now(),
            'steps': []
        }
        
        try:
            # 读取数据
            print("步骤1: 读取数据")
            data = read_func(source, **kwargs)
            result['steps'].append('read')
            
            # 验证数据
            if validate_func:
                print("步骤2: 验证数据")
                validate_func(data, **kwargs)
                result['steps'].append('validate')
            
            # 预处理
            if preprocess_func:
                print("步骤3: 预处理")
                data = preprocess_func(data, **kwargs)
                result['steps'].append('preprocess')
            
            # 核心处理
            print("步骤4: 核心处理")
            processed_data = process_func(data, **kwargs)
            result['steps'].append('process')
            
            # 后处理
            if postprocess_func:
                print("步骤5: 后处理")
                processed_data = postprocess_func(processed_data, **kwargs)
                result['steps'].append('postprocess')
            
            # 保存数据
            print("步骤6: 保存数据")
            save_func(processed_data, target, **kwargs)
            result['steps'].append('save')
            
            # 清理
            if cleanup_func:
                print("步骤7: 清理")
                cleanup_func(**kwargs)
                result['steps'].append('cleanup')
            
            result['success'] = True
            result['duration'] = time.time() - start_time
            
        except Exception as e:
            result['success'] = False
            result['error'] = str(e)
            result['duration'] = time.time() - start_time
            print(f"处理失败: {e}")
        
        result['end_time'] = datetime.now()
        return result
    
    return template_processor


# 函数式处理器示例
def read_text_file(source: str, **kwargs) -> List[str]:
    """读取文本文件"""
    encoding = kwargs.get('encoding', 'utf-8')
    with open(source, 'r', encoding=encoding) as file:
        lines = file.readlines()
    print(f"读取文本文件: {len(lines)}行")
    return lines


def process_text_lines(data: List[str], **kwargs) -> List[str]:
    """处理文本行"""
    processed_lines = []
    for line in data:
        # 清理空白字符，转换为小写
        clean_line = line.strip().lower()
        if clean_line:  # 过滤空行
            processed_lines.append(clean_line)
    
    print(f"处理文本行: {len(data)} -> {len(processed_lines)}行")
    return processed_lines


def save_text_file(data: List[str], target: str, **kwargs) -> None:
    """保存文本文件"""
    encoding = kwargs.get('encoding', 'utf-8')
    os.makedirs(os.path.dirname(target), exist_ok=True)
    
    with open(target, 'w', encoding=encoding) as file:
        for line in data:
            file.write(line + '\n')
    
    print(f"保存文本文件: {target}")


def validate_text_data(data: List[str], **kwargs) -> None:
    """验证文本数据"""
    if not data:
        raise ValueError("文本数据为空")
    
    max_lines = kwargs.get('max_lines', 10000)
    if len(data) > max_lines:
        raise ValueError(f"文本行数超过限制: {len(data)} > {max_lines}")


# ============= 装饰器模板方法 =============

def template_method(*steps):
    """
    装饰器模板方法 - Python特色实现
    
    使用装饰器定义处理步骤
    """
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            print(f"\n装饰器模板方法: {func.__name__}")
            
            result = {
                'function': func.__name__,
                'start_time': datetime.now(),
                'steps': []
            }
            
            try:
                # 执行预定义步骤
                for step_name, step_func in steps:
                    print(f"执行步骤: {step_name}")
                    step_result = step_func(*args, **kwargs)
                    result['steps'].append({
                        'name': step_name,
                        'result': step_result
                    })
                    
                    # 如果步骤返回新的参数，更新kwargs
                    if isinstance(step_result, dict):
                        kwargs.update(step_result)
                
                # 执行主函数
                print(f"执行主函数: {func.__name__}")
                main_result = func(*args, **kwargs)
                result['main_result'] = main_result
                result['success'] = True
                
            except Exception as e:
                result['success'] = False
                result['error'] = str(e)
                print(f"执行失败: {e}")
            
            result['end_time'] = datetime.now()
            return result
        
        return wrapper
    return decorator


# 装饰器步骤函数
def log_start(*args, **kwargs):
    """记录开始"""
    print("开始处理...")
    return {'logged': True}


def check_permissions(*args, **kwargs):
    """检查权限"""
    user = kwargs.get('user', 'anonymous')
    if user == 'anonymous':
        raise PermissionError("需要用户认证")
    print(f"用户 {user} 权限检查通过")
    return {'authorized': True}


def measure_performance(*args, **kwargs):
    """性能测量"""
    start_time = time.time()
    kwargs['_start_time'] = start_time
    print("开始性能测量")
    return {}


def log_end(*args, **kwargs):
    """记录结束"""
    if '_start_time' in kwargs:
        duration = time.time() - kwargs['_start_time']
        print(f"处理完成，耗时: {duration:.2f}秒")
    return {'completed': True}


# 使用装饰器模板方法
@template_method(
    ('log_start', log_start),
    ('check_permissions', check_permissions),
    ('measure_performance', measure_performance),
    ('log_end', log_end)
)
def process_user_data(user_id: str, data: Dict[str, Any], **kwargs):
    """处理用户数据 - 使用装饰器模板"""
    print(f"处理用户 {user_id} 的数据")
    
    # 模拟数据处理
    processed_data = {
        'user_id': user_id,
        'processed_at': datetime.now().isoformat(),
        'data_size': len(str(data)),
        'data': data
    }
    
    return processed_data


# ============= 异步模板方法 =============

class AsyncDataProcessor(ABC):
    """
    异步数据处理器 - 支持异步操作的模板方法
    
    Python特色：
    - 异步模板方法
    - 并发处理支持
    - 异步钩子方法
    """
    
    async def process_data_async(self, source: str, target: str) -> Dict[str, Any]:
        """异步模板方法"""
        print(f"\n异步处理数据: {source} -> {target}")
        
        start_time = time.time()
        result = {
            'source': source,
            'target': target,
            'start_time': datetime.now(),
            'steps': []
        }
        
        try:
            # 异步读取数据
            print("异步读取数据")
            data = await self.read_data_async(source)
            result['steps'].append('read_async')
            
            # 异步验证
            if await self.should_validate_async():
                print("异步验证数据")
                await self.validate_data_async(data)
                result['steps'].append('validate_async')
            
            # 异步处理
            print("异步处理数据")
            processed_data = await self.process_core_logic_async(data)
            result['steps'].append('process_async')
            
            # 异步保存
            print("异步保存数据")
            await self.save_data_async(processed_data, target)
            result['steps'].append('save_async')
            
            result['success'] = True
            result['duration'] = time.time() - start_time
            
        except Exception as e:
            result['success'] = False
            result['error'] = str(e)
            result['duration'] = time.time() - start_time
            print(f"异步处理失败: {e}")
        
        result['end_time'] = datetime.now()
        return result
    
    @abstractmethod
    async def read_data_async(self, source: str) -> Any:
        """异步读取数据"""
        pass
    
    @abstractmethod
    async def process_core_logic_async(self, data: Any) -> Any:
        """异步核心处理逻辑"""
        pass
    
    @abstractmethod
    async def save_data_async(self, data: Any, target: str) -> None:
        """异步保存数据"""
        pass
    
    async def should_validate_async(self) -> bool:
        """异步检查是否需要验证"""
        return True
    
    async def validate_data_async(self, data: Any) -> None:
        """异步验证数据"""
        if not data:
            raise ValueError("数据为空")


class AsyncWebDataProcessor(AsyncDataProcessor):
    """
    异步Web数据处理器
    
    模拟从Web API获取数据并处理
    """
    
    def __init__(self, timeout: float = 10.0):
        self.timeout = timeout
    
    async def read_data_async(self, source: str) -> Dict[str, Any]:
        """异步读取Web数据"""
        # 模拟HTTP请求
        print(f"发起HTTP请求: {source}")
        await asyncio.sleep(0.5)  # 模拟网络延迟
        
        # 模拟返回数据
        data = {
            'url': source,
            'timestamp': datetime.now().isoformat(),
            'data': [{'id': i, 'value': f'item_{i}'} for i in range(10)]
        }
        
        print(f"接收到数据: {len(data['data'])}个项目")
        return data
    
    async def process_core_logic_async(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """异步处理Web数据"""
        # 模拟并发处理
        items = data.get('data', [])
        
        async def process_item(item):
            await asyncio.sleep(0.1)  # 模拟处理时间
            return {
                'id': item['id'],
                'value': item['value'].upper(),
                'processed_at': datetime.now().isoformat()
            }
        
        # 并发处理所有项目
        processed_items = await asyncio.gather(*[process_item(item) for item in items])
        
        result = {
            'original_url': data['url'],
            'processed_at': datetime.now().isoformat(),
            'items': processed_items
        }
        
        print(f"并发处理完成: {len(processed_items)}个项目")
        return result
    
    async def save_data_async(self, data: Dict[str, Any], target: str) -> None:
        """异步保存数据"""
        # 模拟异步文件写入
        await asyncio.sleep(0.2)  # 模拟IO延迟
        
        # 确保目标目录存在
        os.makedirs(os.path.dirname(target), exist_ok=True)
        
        # 写入文件
        with open(target, 'w', encoding='utf-8') as file:
            json.dump(data, file, indent=2, ensure_ascii=False)
        
        print(f"异步保存完成: {target}")


# ============= 演示函数 =============

def demonstrate_traditional_template():
    """
    演示传统模板方法模式
    
    概述引导：
    展示传统模板方法模式的实现，包括抽象基类、具体实现类
    和钩子方法的使用。
    
    学习要点：
    1. 模板方法的定义
    2. 抽象方法和钩子方法
    3. 算法骨架的固定
    4. 子类的定制化实现
    
    关键理解：
    模板方法定义算法结构，子类实现具体步骤。
    """
    print("=== 传统模板方法模式演示 ===")
    print("\n学习目标：")
    print("- 理解模板方法的结构")
    print("- 掌握抽象方法和钩子方法")
    print("- 学习算法骨架的设计")
    print("\n重点概念：")
    print("- 算法骨架固定")
    print("- 步骤实现可变")
    print("- 钩子方法可选")
    print("=" * 50)
    
    # 创建测试数据
    test_data_dir = "temp_test_data"
    os.makedirs(test_data_dir, exist_ok=True)
    
    # 创建CSV测试文件
    csv_file = os.path.join(test_data_dir, "test.csv")
    with open(csv_file, 'w', encoding='utf-8') as f:
        f.write("Name,Age,City\n")
        f.write("Alice,25,New York\n")
        f.write("Bob,30,London\n")
        f.write("Charlie,35,Tokyo\n")
        f.write("  ,  ,  \n")  # 空行测试
        f.write("David,28,Paris\n")
    
    # 创建JSON测试文件
    json_file = os.path.join(test_data_dir, "test.json")
    test_json_data = {
        "users": [
            {"Name": "Alice", "Age": 25, "City": "New York"},
            {"Name": "Bob", "Age": 30, "City": "London"}
        ],
        "metadata": {
            "created": "2024-01-01",
            "version": "1.0"
        }
    }
    with open(json_file, 'w', encoding='utf-8') as f:
        json.dump(test_json_data, f, indent=2)
    
    # 测试CSV处理器
    print("\n=== CSV处理器测试 ===")
    csv_processor = CSVProcessor()
    csv_result = csv_processor.process_data(
        csv_file, 
        os.path.join(test_data_dir, "processed.csv")
    )
    print(f"CSV处理结果: {csv_result}")
    
    # 测试JSON处理器
    print("\n=== JSON处理器测试 ===")
    json_processor = JSONProcessor()
    json_processor.set_schema({'type': 'object'})  # 设置简单schema
    json_result = json_processor.process_data(
        json_file,
        os.path.join(test_data_dir, "processed.json")
    )
    print(f"JSON处理结果: {json_result}")
    
    # 清理测试文件
    import shutil
    shutil.rmtree(test_data_dir)
    print("\n清理测试文件完成")


def demonstrate_functional_template():
    """
    演示函数式模板方法
    """
    print("\n=== 函数式模板方法演示 ===")
    
    # 创建函数式处理器
    text_processor = create_template_processor(
        read_func=read_text_file,
        process_func=process_text_lines,
        save_func=save_text_file,
        validate_func=validate_text_data
    )
    
    # 创建测试数据
    test_dir = "temp_functional_test"
    os.makedirs(test_dir, exist_ok=True)
    
    test_file = os.path.join(test_dir, "test.txt")
    with open(test_file, 'w', encoding='utf-8') as f:
        f.write("Hello World\n")
        f.write("PYTHON Programming\n")
        f.write("\n")  # 空行
        f.write("  Template Method  \n")
        f.write("Design Pattern\n")
    
    # 使用函数式处理器
    result = text_processor(
        test_file,
        os.path.join(test_dir, "processed.txt"),
        encoding='utf-8',
        max_lines=100
    )
    
    print(f"函数式处理结果: {result}")
    
    # 读取处理后的文件
    with open(os.path.join(test_dir, "processed.txt"), 'r', encoding='utf-8') as f:
        processed_content = f.read()
    print(f"\n处理后内容:\n{processed_content}")
    
    # 清理
    import shutil
    shutil.rmtree(test_dir)


def demonstrate_decorator_template():
    """
    演示装饰器模板方法
    """
    print("\n=== 装饰器模板方法演示 ===")
    
    # 测试用户数据处理
    test_data = {
        'name': 'Alice',
        'email': 'alice@example.com',
        'preferences': ['python', 'design_patterns']
    }
    
    # 正常处理
    print("\n正常处理:")
    result = process_user_data(
        user_id='user123',
        data=test_data,
        user='alice'  # 提供用户认证
    )
    print(f"处理结果: {result}")
    
    # 权限错误测试
    print("\n权限错误测试:")
    result = process_user_data(
        user_id='user456',
        data=test_data
        # 不提供用户认证
    )
    print(f"错误处理结果: {result}")


async def demonstrate_async_template():
    """
    演示异步模板方法
    """
    print("\n=== 异步模板方法演示 ===")
    
    # 创建异步处理器
    async_processor = AsyncWebDataProcessor(timeout=5.0)
    
    # 创建测试目录
    test_dir = "temp_async_test"
    os.makedirs(test_dir, exist_ok=True)
    
    # 异步处理数据
    result = await async_processor.process_data_async(
        "https://api.example.com/data",
        os.path.join(test_dir, "async_result.json")
    )
    
    print(f"异步处理结果: {result}")
    
    # 读取结果文件
    result_file = os.path.join(test_dir, "async_result.json")
    if os.path.exists(result_file):
        with open(result_file, 'r', encoding='utf-8') as f:
            saved_data = json.load(f)
        print(f"\n保存的数据项目数: {len(saved_data.get('items', []))}")
    
    # 清理
    import shutil
    shutil.rmtree(test_dir)


def demonstrate_java_comparison():
    """
    Java对比演示
    
    Java等价代码：
    ```java
    // Java版本的模板方法模式
    public abstract class DataProcessor {
        // 模板方法
        public final ProcessResult processData(String source, String target) {
            ProcessResult result = new ProcessResult();
            
            try {
                // 步骤1: 读取数据
                Object data = readData(source);
                
                // 步骤2: 验证数据（钩子方法）
                if (shouldValidate()) {
                    validateData(data);
                }
                
                // 步骤3: 处理数据
                Object processedData = processCoreLogic(data);
                
                // 步骤4: 保存数据
                saveData(processedData, target);
                
                result.setSuccess(true);
            } catch (Exception e) {
                result.setSuccess(false);
                result.setError(e.getMessage());
            }
            
            return result;
        }
        
        // 抽象方法
        protected abstract Object readData(String source) throws Exception;
        protected abstract Object processCoreLogic(Object data) throws Exception;
        protected abstract void saveData(Object data, String target) throws Exception;
        
        // 钩子方法
        protected boolean shouldValidate() {
            return true;
        }
        
        protected void validateData(Object data) throws Exception {
            if (data == null) {
                throw new IllegalArgumentException("Data is null");
            }
        }
    }
    
    // 具体实现
    public class CSVProcessor extends DataProcessor {
        @Override
        protected Object readData(String source) throws Exception {
            // CSV读取逻辑
            return csvData;
        }
        
        @Override
        protected Object processCoreLogic(Object data) throws Exception {
            // CSV处理逻辑
            return processedData;
        }
        
        @Override
        protected void saveData(Object data, String target) throws Exception {
            // CSV保存逻辑
        }
    }
    ```
    
    Python优势：
    1. 函数式模板方法
    2. 装饰器模板方法
    3. 异步模板方法支持
    4. 更灵活的钩子机制
    """
    print("\n=== Java对比说明 ===")
    print("\nPython优势：")
    print("1. 函数式模板方法 - 使用函数组合")
    print("2. 装饰器模板方法 - 声明式步骤定义")
    print("3. 异步模板方法 - 原生异步支持")
    print("4. 更灵活的钩子机制")
    print("5. 动态步骤配置")
    
    print("\nJava特点：")
    print("1. final模板方法防止重写")
    print("2. 强类型的方法签名")
    print("3. 编译时检查")
    print("4. 更明确的继承关系")
    
    # 演示Python的灵活性
    print("\n=== Python灵活性演示 ===")
    
    # 动态创建处理步骤
    def create_dynamic_processor(steps: List[str]):
        """动态创建处理器"""
        def dynamic_processor(data):
            result = data
            for step in steps:
                if step == 'uppercase':
                    result = result.upper() if isinstance(result, str) else result
                elif step == 'reverse':
                    result = result[::-1] if isinstance(result, str) else result
                elif step == 'strip':
                    result = result.strip() if isinstance(result, str) else result
                print(f"执行步骤: {step}")
            return result
        return dynamic_processor
    
    # 使用动态处理器
    processor = create_dynamic_processor(['strip', 'uppercase', 'reverse'])
    result = processor("  hello world  ")
    print(f"动态处理结果: '{result}'")


def performance_comparison():
    """
    性能对比测试
    """
    print("\n=== 性能对比 ===")
    
    # 创建测试数据
    test_data = [f"line {i}" for i in range(1000)]
    
    # 测试传统模板方法性能
    print("\n传统模板方法性能测试:")
    
    class SimpleProcessor(DataProcessor):
        def read_data(self, source: str):
            return test_data
        
        def process_core_logic(self, data):
            return [line.upper() for line in data]
        
        def save_data(self, data, target: str):
            pass  # 不实际保存
    
    processor = SimpleProcessor()
    
    start_time = time.time()
    for i in range(100):
        processor.process_data("test", "test")
    traditional_time = time.time() - start_time
    print(f"传统模板方法 (100次处理): {traditional_time:.4f}秒")
    
    # 测试函数式模板方法性能
    print("\n函数式模板方法性能测试:")
    
    def simple_read(source, **kwargs):
        return test_data
    
    def simple_process(data, **kwargs):
        return [line.upper() for line in data]
    
    def simple_save(data, target, **kwargs):
        pass
    
    functional_processor = create_template_processor(
        simple_read, simple_process, simple_save
    )
    
    start_time = time.time()
    for i in range(100):
        functional_processor("test", "test")
    functional_time = time.time() - start_time
    print(f"函数式模板方法 (100次处理): {functional_time:.4f}秒")
    
    # 测试装饰器模板方法性能
    print("\n装饰器模板方法性能测试:")
    
    @template_method(
        ('step1', lambda *args, **kwargs: {}),
        ('step2', lambda *args, **kwargs: {})
    )
    def simple_decorator_process(data):
        return [line.upper() for line in data]
    
    start_time = time.time()
    for i in range(100):
        simple_decorator_process(test_data)
    decorator_time = time.time() - start_time
    print(f"装饰器模板方法 (100次处理): {decorator_time:.4f}秒")
    
    print(f"\n性能对比:")
    print(f"传统模板方法: {traditional_time:.4f}秒")
    print(f"函数式模板方法: {functional_time:.4f}秒")
    print(f"装饰器模板方法: {decorator_time:.4f}秒")
    
    # 计算相对性能
    baseline = min(traditional_time, functional_time, decorator_time)
    print(f"\n相对性能 (以最快为基准):")
    print(f"传统模板方法: {traditional_time / baseline:.2f}x")
    print(f"函数式模板方法: {functional_time / baseline:.2f}x")
    print(f"装饰器模板方法: {decorator_time / baseline:.2f}x")


async def main():
    """主函数"""
    demonstrate_traditional_template()
    demonstrate_functional_template()
    demonstrate_decorator_template()
    await demonstrate_async_template()
    demonstrate_java_comparison()
    performance_comparison()


if __name__ == "__main__":
    asyncio.run(main())